home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr44 / ppl4c10.zip / PPL4C.DOC < prev    next >
Text File  |  1995-02-12  |  53KB  |  1,770 lines
  1.  
  2.  
  3.                     Personal Protocol Library
  4.  
  5.                            For C/C++
  6.  
  7.  
  8.                              (PCL4C)
  9.  
  10.  
  11.  
  12.                           USERS MANUAL
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                            Version  1.0
  19.  
  20.                          February 12, 1995
  21.  
  22.  
  23.  
  24.  
  25.                  This software is provided as-is.
  26.           There are no warranties, expressed or implied.
  27.  
  28.  
  29.  
  30.  
  31.                        Copyright (C) 1995
  32.                        All rights reserved
  33.  
  34.  
  35.  
  36.                        MarshallSoft Computing, Inc.
  37.                        Post Office Box 4543
  38.                        Huntsville AL 35815
  39.  
  40.                        Voice 205-881-4630
  41.                        FAX   205|880|0925
  42.                        BBS   205-880-9748
  43.  
  44.  
  45.  
  46.  
  47.                                 _______
  48.                            ____|__     |                (R)
  49.                         --+       |    +-------------------
  50.                           |   ____|__  |  Association of
  51.                           |  |       |_|  Shareware
  52.                           |__|   o   |    Professionals
  53.                         --+--+   |   +---------------------
  54.                              |___|___|    MEMBER
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  PPL4C Users Manual                                                Page 1
  69.                        C O N T E N T S
  70.  
  71.  
  72.  
  73.  
  74.  
  75.     Chapter                                                   Page
  76.  
  77.     1.0 Introduction................................................3
  78.         1.1 User Support............................................3
  79.         1.2 ASP Ombudsman...........................................3
  80.         1.3 Installation............................................4
  81.     2.0 Library Organization........................................5
  82.         2.1 Performance.............................................5
  83.     3.0 Protocol Intefaces..........................................6
  84.         3.1 ASCII API...............................................6
  85.         3.2 XMODEM API..............................................7
  86.         3.3 YMODEM API..............................................8
  87.         3.4 ZMODEM API..............................................9
  88.     4.0 Protocol Demonstration Program (TERM)......................10
  89.     5.0 XMODEM Protocol Overview...................................11
  90.         5.1 XMODEM/CRC.............................................13
  91.         5.2 XMODEM/1K..............................................13
  92.     6.0 YMODEM Protocol Overview...................................14
  93.     7.0 ZMODEM Protocol Overview...................................15
  94.         7.1 Introduction...........................................15
  95.         7.2 Link Escape Encoding...................................15
  96.         7.3 ZMODEM Headers.........................................15
  97.         7.4 Binary Data Subpackets.................................16
  98.         7.5 ZMODEM Startup.........................................16
  99.         7.6 File Transmission......................................17
  100.         7.7 ZMODEM Termination.....................................17
  101.         7.8 ZMODEM Streaming.......................................17
  102.         7.9 ZMODEM Attention Sequence..............................18
  103.         7.10 Frame Types...........................................18
  104.              ZRQINT,ZRINIT,ZSINIT,ZACK.............................18
  105.              ZFILE.................................................19
  106.              ZSKIP,ZNAK,ZABORT,ZFIN,ZRPOS..........................20
  107.              ZDATA,ZEOF,ZFERR,ZCRC.................................20
  108.              ZCHALLENGE,ZCOMPL,ZCAN,ZFREECNT,ZCOMMAND..............21
  109.         7.11 Examples..............................................22
  110.         7.12 ZFILE Frame Information...............................22
  111.     8.0 Problems...................................................23
  112.     9.0 Legal Issues...............................................24
  113.         9.1 Registration...........................................24
  114.         9.2 License................................................25
  115.         9.3 Warranty...............................................25
  116.    10.1 Revision History...........................................26
  117.    11.0 Other MarshallSoft Computing products for Pascal...........26
  118.         11.1 The Personal Communications Library for Pascal........26
  119.         11.2 The LZW Data Compression Library for Pascal...........26
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  PPL4C Users Manual                                                Page 2
  137.   1.0 Introduction
  138.  
  139.   The  Personal  Protocol Library for C/C++ (PPL4C) consists of ASCII, XMODEM,
  140.   YMODEM, and ZMODEM protocol routines plus the example terminal program  TERM
  141.   and  support  routines such as CRC calculation codes. Source is supplied for
  142.   all routines except for the ZMODEM  code  which  requires  registration  for
  143.   source code.
  144.  
  145.   The PPL4C also requires the Personal Communications Library (PCL4C).
  146.  
  147.   1.1 User Support
  148.  
  149.   We want you to be successful in developing your applications using PPL4C! We
  150.   depend on our customers to let us know what they need in a protocol library.
  151.   This means we are committed to providing the best protocol library  that  we
  152.   can. If you have any suggestions or comments, please let us know!
  153.  
  154.   We provide customer support for registered customers by voice, FAX, BBS, and
  155.   mail.  We provide limited support for unregistered users by  voice  and  BBS
  156.   only.
  157.  
  158.   If  you  are  having  a problem using PPL4C, call us at 205-881-4630 between
  159.   1:30 PM and 9:30 PM (CST) Monday through Friday. You can also call at  other
  160.   times and leave a message, and call back later for a reply. Registered users
  161.   (ONLY) can also FAX us at 205-880-0925 at any time (24 hours).
  162.  
  163.   However,  we  can  only  answer  questions  with  respect to using the PPL4C
  164.   library.  We cannot help you program your application, but we'll be glad  to
  165.   discuss it with you.
  166.  
  167.   You  may  also  call  our User Support BBS (2400 to 14400 baud, no parity, 8
  168.   data bits, 1 stop bit) at 205-880-9748 and leave a message  (address  it  to
  169.   the SYSOP).  We will usually have a reply ready for you within 24 hours.
  170.  
  171.   The BBS is available 24 hours per day. All files are in standard ZIP format.
  172.   The  BBS  will  contain  the  latest  shareware  version of all MarshallSoft
  173.   Computing products as well as related files such as:
  174.  
  175.       BUGS.ZIP     -  Bug report.
  176.       NEWS.ZIP     |  Latest news regarding our products.
  177.       PRODUCTS.ZIP -  List of all shareware products.
  178.  
  179.   The  MarshallSoft  Computing,  Inc.   newsletter  "Comm  Talk"  is published
  180.   quarterly.  It discusses various communications problems and solutions using
  181.   PPL4C as well as related information. Registered users (in the  US)  receive
  182.   a  one  year  complimentary subscription when first registering and for each
  183.   update purchased.
  184.  
  185.  
  186.   1.2 ASP Ombudsman
  187.  
  188.  
  189.   MarshallSoft Computing, Inc.  is a member of the  Association  of  Shareware
  190.   Professionals  (ASP).   ASP  wants to make sure that the shareware principle
  191.   works for you.  If you are unable to  resolve  a  shareware-related  problem
  192.   with  an  ASP  member  by contacting the member directly, ASP may be able to
  193.   help. The ASP Ombudsman can help you resolve a dispute or  problem  with  an
  194.   ASP  member,  but  does not provide technical support for members' products.
  195.   Please write to the ASP Ombudsman at  545  Grover  Road,  Muskegon,  MI  USA
  196.   49442-9427,  Fax  616-788-2765,  or send a CompuServe message via CompuServe
  197.   Mail to ASP Ombudsman 70007,3536.
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  PPL4C Users Manual                                                Page 3
  205.   1.3 Installation
  206.  
  207.  
  208.   (1) PPL4C requires the Personal Communications Library for C/C++ (PCL4C).
  209.   If  you don't already have it, you may download it from our user support BBS
  210.   at 205-880-9748.
  211.  
  212.   (2) Before installation of PPL4C, your compiler should already be  installed
  213.   on  your system and tested. If you are not familiar with makefiles, refer to
  214.   your compiler manual.
  215.  
  216.   (3)  Make  a  backup  copy  of  your  distribution  disk.  Put your original
  217.   distribution disk in a safe place.
  218.  
  219.   (4) Create a empty directory on your work disk (normally your harddisk).  For
  220.   example,  to create a work directory named PPL4C, we first log onto the work
  221.   disk and then type:
  222.  
  223.                    MKDIR PPL4C
  224.  
  225.   (5)  Copy  all  the  files from your backup copy of the distribution disk to
  226.   your PPL4C work directory.  For example, to copy from the A: drive  to  your
  227.   work directory, we type:
  228.  
  229.                   CD PPL4C
  230.                   COPY A:*.*
  231.  
  232.   (6) Your must copy PCL4C_*.LIB (PCL4C_*.MIX if using Power C) and PCL4C.H to
  233.   your PPL4C work directory from your PCL4C  distribution  disk  in  order  to
  234.   compile  the  TERM protocol demonstration program.  Don't combine files from
  235.   the PCL4C distribution disk and  the  PPL4C  distribution  disk  other  than
  236.   coping PCL4C_*.LIB and PCL4C.H.
  237.  
  238.   (7) Compile the  TERM.C  protocol  demonstration  program.   Note  that  the
  239.   shareware version of ZMODEM.C is in "shrouded source" form.
  240.  
  241.                   make -fterm._T_      (for Turbo C/C++)
  242.                   make -fterm._B_      (for Borland C/C++)
  243.                   make term._M_        (for Microsoft C/C++)
  244.                   pc/e term            (for MIX Power C)
  245.  
  246.  
  247.   (8)  To test TERM type TERM followed by the port and baud rate. For example,
  248.   to start TERM on COM1 at 38400 baud, type:
  249.  
  250.                   TERM 1 38400
  251.  
  252.   Test TERM by connecting COM1 to a modem or another  PC  with  a  null  modem
  253.   cable.
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  PPL4C Users Manual                                                Page 4
  273.   2.0 Library Organization
  274.  
  275.  
  276.   The library is composed of two parts as follows:
  277.  
  278.   (1)  The  copyrighted  XMODEM, YMODEM, and ZMODEM functions contained in the
  279.   files:
  280.  
  281.   xymodem.c
  282.   xypacket.c
  283.   zmodem.c
  284.  
  285.   The shareware version of ZMODEM.C is in "shrouded source" form. This means
  286.   that the source code can be compiled but not easily modified. The registered
  287.   user will have "normal source".
  288.  
  289.   (2) The public domain example code contained in the files:
  290.  
  291.   term.c     term_io.c    amodem.c    modem_io.c
  292.   crc16.c    crc32.c      defines.c   si.c
  293.   opcodes.c  zdate.c      datetime.c  dir_io.c
  294.  
  295.  
  296.   2.1 Performance
  297.  
  298.   XMODEM, YMODEM, and ZMODEM were timed in transfers between a 386 and  a  486
  299.   using  a  null  modem  cable.  The  timed results for a 10,000 byte files in
  300.   characters per second (CPS) transfered are as follows:
  301.  
  302.              2400    9600    19200    38400
  303.   XMODEM      193     590     1256     2514
  304.   YMODEM      228     773     1671     3351
  305.   ZMODEM      220     860     1800     3004
  306.  
  307.   Your results may vary depending on the type of hardware used, but the  above
  308.   should be fairly close.
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  PPL4C Users Manual                                                Page 5
  341.   3.0 Protocol Interfaces
  342.  
  343.  
  344.   The API (Application Programming Interface) is documented for the  following
  345.   four protocols: ASCII, XMODEM, YMODEM, and ZMODEM.
  346.  
  347.  
  348.   3.1 ASCII API
  349.  
  350.  
  351.   ASCII  is  not realy a "protocol" but rather a loosely agreed upon method of
  352.   transferring ASCII files. The ASCII protocol is contained in AMODEM.C.
  353.  
  354.  
  355.   int TxAscii(
  356.       int  Port,        /* COM port [0..19] */
  357.       char *Filename,   /* filename buffer */
  358.       int  CharPace,    /* delay between characters in tics */
  359.       char TermChar,    /* termination character (0x00 if none) */
  360.       int  TimeOut,     /* delay after which assume sender is done */
  361.       int  EchoFlag)    /* local echo flag */
  362.  
  363.  
  364.   int RxAscii(
  365.       int  Port,        /* COM port [0..19] */
  366.       char *Filename,   /* filename buffer */
  367.       char TermChar,    /* termination character (0x00 if none) */
  368.       int  TimeOut,     /* delay after which assume sender is done */
  369.       int  EchoFlag)    /* local echo flag */
  370.  
  371.   Note the following:
  372.  
  373.   (1) The Filename must not contain any path information.
  374.  
  375.   (2) TermPace should in general be 1 to 5 timer tics (18.2 tics per second).
  376.  
  377.   (3) TermChar is often set to escape (0x1B) or control-X (0x18). If both  sides
  378.   don't agree, it is best not use a termination character.
  379.  
  380.   (4) TimeOut should be set to from 3 to 10 seconds.
  381.  
  382.   (5) The receiver side (RxAscii) should be started before the sender side.
  383.  
  384.   Refer to the TERM.C program for an example of calling TxAscii and RxAscii.
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  PPL4C Users Manual                                                Page 6
  409.   3.2 XMODEM API
  410.  
  411.  
  412.   XMODEM is the first well accepted protocol. There are many places  where  it
  413.   is still the only choice for transferring binary files.
  414.  
  415.   The  XMODEM protocol is contained in XYMODEM.C and XYPACKET.C. There are
  416.   two main variants of XMODEM in addition to standard XMODEM as follows:
  417.  
  418.  
  419.         Protocol    OneKflag   NCGbyte
  420.         XMODEM       False      NAK
  421.         XMODEM-CRC   False      'C'
  422.         XMODEM-1K    True       'C'
  423.  
  424.  
  425.   int XmodemTx(
  426.       int  Port,        /* COM port [0..19] */
  427.       char *Filename,   /* filename buffer */
  428.       int  OneKflag)    /* 1K flag */
  429.  
  430.  
  431.   int  XmodemRx(
  432.       int  Port,        /* COM port [0..19] */
  433.       char *Filename,   /* filename buffer */
  434.       char NCGbyte)     /* NAK or 'C' */
  435.  
  436.  
  437.   Refer to the TERM.C program for an example of calling XMODEM.
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  PPL4C Users Manual                                                Page 7
  477.   3.3 YMODEM API
  478.  
  479.  
  480.   The YMODEM protocol (also referred to as "YMODEM/BATCH") is a batch protocol
  481.   capable  of sending multiple files along with their filename, size, and date
  482.   of last modification.  It also can send 1024 byte packets in addition to 128
  483.   byte XMODEM packets. The YMODEM protocol is  contained  in  XYMODEM.C  and
  484.   XYPACKET.C.
  485.  
  486.   There is one variant of YMODEM called YMODEM-G  which  is  used  with  error
  487.   correcting  modems  only. Flow control is also  required  in  order  to  use
  488.   YMODEM-G.
  489.  
  490.  
  491.         Protocol    OneKflag   NCGbyte
  492.         YMODEM       True       'C'
  493.         YMODEM-G     True       'G'
  494.  
  495.  
  496.   int YmodemTx(
  497.       int  Port,        /* COM port [0..19] */
  498.       char *Filename,   /* filename buffer */
  499.       int  OneKflag)    /* 1K flag */
  500.  
  501.  
  502.   int YmodemRx(
  503.       int  Port,        /* COM port [0..19] */
  504.       char *Filename,   /* filename buffer */
  505.       char NCGbyte)     /* NAK or 'C' */
  506.  
  507.   Refer to the TERM.C program for an example of calling YMODEM.
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  PPL4C Users Manual                                                Page 8
  545.   3.4 ZMODEM API
  546.  
  547.  
  548.   The  Stream  variable  controls  rather  Zmodem will attempt to send packets
  549.   without  any  acknowlegement. Set Stream to false for high baud rates (38400
  550.   and above) or for noisy lines.
  551.  
  552.   The ZMODEM protocol is contained in ZMODEM.C.
  553.  
  554.  
  555.   int ZmodemTx(
  556.       int  Port,        /* COM port [0..19] */
  557.       char *Filename,   /* filename buffer */
  558.       int  Stream)      /* Can do streaming ? */
  559.  
  560.  
  561.   int ZmodemRx(
  562.       int  Port,        /* COM port [0..19] */
  563.       char *Filename,   /* filename buffer */
  564.       int  Stream)      /* Can do streaming ? */
  565.  
  566.  
  567.   Refer to the TERM.C program for an example of calling ZMODEM.
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  PPL4C Users Manual                                                Page 9
  613.   4.0 Protocol Demonstration Program (TERM)
  614.  
  615.  
  616.   TERM is an communications program suitable for  calling  up  bulletin  board
  617.   systems  (BBS)  and performing as a PC to PC file copy program.  TERM itself
  618.   is not part of the communications library, but rather it is provided  as  an
  619.   example of a communications application using PPL4C.
  620.  
  621.   TERM can send a standard Hayes standard AT command set string to your modem.
  622.   An  initialization  string  is  sent by TERM provided that AT_COMMAND_SET is
  623.   defined in TERM.CFG.
  624.  
  625.        #define AT_COMMAND_SET 1
  626.  
  627.   Refer  to  the chapter "Modem Initialization" in the Personal Communications
  628.   Library Users Manual for a discussion of initialization strings.
  629.  
  630.   TERM also supports hardware flow control (RTS/CTS). Hardware flow control is
  631.   observed provided that the constant RTS_CTS_CONTROL is defined in  the  file
  632.   TERM.CFG.
  633.  
  634.        #define RTS_CTS_CONTROL 1
  635.  
  636.   Refer  to  the chapter "Flow Control" in the Personal Communications Library
  637.   Users Manual for a discussion of hardware flow control.
  638.  
  639.   TERM can be configured to run script files by setting
  640.  
  641.        #define SCRIPTS 1
  642.  
  643.   in TERM.CFG.  Refer to the SCRIPTS.DOC file for information on scripts.
  644.  
  645.   TERM can exchange files using ASCII XMODEM, YMODEM and ZMODEM communications
  646.   protocols.  TERM can accept wildcards in the filename so that multiple files
  647.   can  be  sent  using  YMODEM  and  ZMODEM.   The protocol timing can also be
  648.   adjusted  (this  should  not  be  necessary)  by  modifying  the   constants
  649.   SHORT_WAIT and LONG_WAIT in the PPL4C.C file.
  650.  
  651.   TERM  can  also  be  used  as a PC to PC transfer program using a null modem
  652.   cable.  In this case,  AT_COMMAND_SET  and  RTS_CTS_CONTROL  should  not  be
  653.   defined in the file TERM.CFG:
  654.  
  655.   Be advised that many null modem cables are do NOT swap RTS and CTS, which is
  656.   necessary  for hardware flow control. This means that RTS_CTS_CONTROL should
  657.   never be defined when using a null modem cable  unless  you  are  absolutely
  658.   sure that RTS and CTS are swapped.
  659.  
  660.   To start TERM, type TERM followed by the port (1 to 4)  and  the  baud  rate
  661.   (300,  600,  1200,  2400,  4800,  9600, 19200, 38400, 57600, or 115200). For
  662.   example, to start TERM at 2400 baud on port COM4:
  663.  
  664.        TERM 4 2400
  665.  
  666.   The TERM program (but not the PPL4C protocol routines)  are  placed  in  the
  667.   public  domain  by  MarshallSoft Computing, Inc., and can be used in any way
  668.   desired by the user.
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  PPL4C Users Manual                                                Page 10
  681.   5.0 XMODEM
  682.  
  683.  
  684.   XMODEM  refers  to the file transfer protocol introduced by Ward Christensen
  685.   in 1977.  XMODEM is widely supported on most all bulletin board systems.
  686.  
  687.   The following ASCII character definitions are used in XMODEM.
  688.  
  689.   <SOH> = 01H Is always the first  byte  in  each  block.
  690.   <EOT> =  04H  Sent  instead of SOH to mark the end of transmission.
  691.   <ACK> = 06H Positive acknowledgment.
  692.   <NAK> = 15H Negative acknowledgment.
  693.   <CAN> = 18H Cancel transfer.
  694.  
  695.   XMODEM is a receiver driven, asynchronous, 8 data bit protocol. Each  packet
  696.   looks like the following:
  697.  
  698.   <SOH> <packet #> <compliment #> <data> <checksum>
  699.  
  700.   where:
  701.  
  702.   <SOH>         = 01H
  703.   <packet #>    = Packet number, starting at 01, incrementing by 1,
  704.                   and wraps from 0FFH to 00H (not to 01H).
  705.   <compliment #>= 255 minus the packet number.
  706.   <data>        = 128 bytes of binary data.
  707.   <checksum>    = The sum of the data bytes. Starting with a zero
  708.                   add each data byte to the checksum. Use only the
  709.                   rightmost 8 bits.
  710.  
  711.   When  the  receiver  is  ready,  it  sends a NAK every 10 seconds (up to one
  712.   minute) until the NAK is ackowledged by the transmitter by sending the first
  713.   packet. The transmitter continues by sending each  packet  in  turn,  always
  714.   waiting  for  the  packet to be ackowleged before sending the next. Finally,
  715.   when the transmitter has no more data, it sends an EOT instead of a  SOH  to
  716.   complete the transfer.
  717.  
  718.   Each packet is sent by the transmitter as follows:
  719.  
  720.   (1) Each packet always starts with a SOH.
  721.  
  722.   (2) The packet number is sent next, starting with 01H, and  incrementing  by
  723.   1. The packet number wraps from 0FFH to 00H.
  724.  
  725.   (3)  The  packet  number compliment is sent next.  It is always calculated a
  726.   255 minus the packet number.
  727.  
  728.   (4) Exactly 128 bytes of data is sent.  If the transmitter doesn't have  128
  729.   bytes of data to send, then control-Z's (1AH) are padded to the data block.
  730.  
  731.   (5)  The  checksum  is  calculated  by added together all 128 data bytes and
  732.   sending the least significant 8 bits.
  733.  
  734.   (6)  The  transmitter  waits  (up  to  10  seconds)  for a response.  If the
  735.   response is an ACK, then the transmitter goes on to the next packet.  If the
  736.   response is a NAK, then the transmitter re-sends the entire packet.  If  the
  737.   response is a CAN, then all further transmission is cancelled.
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  PPL4C Users Manual                                                Page 11
  749.   Each packet is handled by the receiver as follows:
  750.  
  751.   (1) If the first character is an EOT then the transfer is now complete,  and
  752.   the  receiver  should ACK the EOT before exitting. If the first character is
  753.   a CAN, then all further action is cancelled. If the  first  character  is  a
  754.   SOH, then this is the first character of the next packet.
  755.  
  756.   (2)  If  the packet number is not correct (the first packet is 1), then this
  757.   is a fatal error, and the receiver should send a CAN to the  transmitter  in
  758.   order to cancel further transmission.
  759.  
  760.   (3) If the packet number compliment is not correct, this  is  also  a  fatal
  761.   error and the receiver sends a CAN to the transmitter.
  762.  
  763.   (4) Exactly 128 bytes of data are received.
  764.  
  765.   (5)  The  checksum  is  received.  It is compared with the value obtained by
  766.   computing the checksum from the just received data.  If the checksum  values
  767.   are the same, an ACK to sent to the transmitter. Otherwise, a NAK is sent.
  768.  
  769.   Here  is a XMODEM example of the data flow.  It includes the two most common
  770.   line hits: a garbaged block, and an <ACK> reply  getting  garbaged.   <data>
  771.   represent 128 bytes of data.  <CS> represents the checksum byte.
  772.  
  773.   SENDER                                 RECEIVER
  774.  
  775.                                               <NAK>
  776.   <SOH> 01 FE <data> <CS>
  777.                                               <ACK>
  778.   <SOH> 02 FD <data> <CS>              (data gets line hit)
  779.                                               <NAK>
  780.   <SOH> 02 FD <data> <CS>
  781.                                               <ACK>
  782.   <SOH> 03 FC <data> <CS>
  783.   (ACK gets garbaged)                         <ACK>
  784.   <SOH> 03 FC <data> <CS>                     <ACK>
  785.   <EOT>
  786.                                        <anything except ACK>
  787.   <EOT>
  788.                                               <ACK>
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  PPL4C Users Manual                                                Page 12
  817.   5.1 XMODEM/CRC Protocol
  818.  
  819.  
  820.   The  XMODEM/CRC  protocol is similar to the XMODEM protocol, except that the
  821.   receiver specifies CRC-16  by  sending  C  (Hex  43)  instead  of  NAK  when
  822.   requesting the FIRST block.  A two byte CRC is sent in place of the one byte
  823.   arithmetic checksum.
  824.  
  825.  
  826.   5.2 XMODEM/1K Protocol
  827.  
  828.  
  829.   The XMODEM/1K protocol is identical to XMODEM/CRC,  except  that  1024  byte
  830.   data  blocks  in addition to 128 byte data blocks can be sent.  An STX (02H)
  831.   replaces the SOH (01H) at the beginning of the transmitted block  to  notify
  832.   the  receiver  of  the  longer block length.  The transmitted block contains
  833.   1024 bytes of data.  The receiver should be able to accept  any  mixture  of
  834.   128  and  1024 byte blocks.  The block number (in the second and third bytes
  835.   of the block) is incremented by one for each block regardless of  the  block
  836.   length.
  837.  
  838.   The sender must not change between 128 and 1024 byte block lengths if it has
  839.   not received a valid ACK for the current block.
  840.  
  841.   Here is an example of XMODEM/1K with 1024 blocks:
  842.  
  843.  
  844.   SENDER                                 RECEIVER
  845.  
  846.                                           C
  847.   STX 01 FE Data[1024] CRC CRC
  848.                                           ACK
  849.   STX 02 FD Data[1024] CRC CRC
  850.                                           ACK
  851.   STX 03 FC Data[1000] ^Z[24] CRC CRC
  852.                                           ACK
  853.   EOT
  854.                                           ACK
  855.  
  856.   Mixed 1024 and 128 byte Blocks
  857.  
  858.  
  859.   SENDER                                 RECEIVER
  860.                                            C
  861.   STX 01 FE Data[1024] CRC CRC
  862.                                           ACK
  863.   STX 02 FD Data[1024] CRC CRC
  864.                                           ACK
  865.   SOH 03 FC Data[128] CRC CRC
  866.                                           ACK
  867.   SOH 04 FB Data[100] ^Z[28] CRC CRC
  868.                                           ACK
  869.   EOT
  870.                                           ACK
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  PPL4C Users Manual                                                Page 13
  885.   6.0 YMODEM Protocol
  886.  
  887.  
  888.   The  YMODEM  Batch  protocol  is an extension to the XMODEM/1K protocol that
  889.   allows 0 or more files to be transmitted in a single session. YMODEM  always
  890.   sends  an  information  packet  (number  0)  with  each  file containing the
  891.   filename and the file length.
  892.  
  893.   The filename is sent as  a  null  terminated  ASCII  string.   This  is  the
  894.   filename format used by the handle oriented MSDOS ints.
  895.  
  896.   The  length  field  is sent as a decimal ascii string counting the number of
  897.   data bytes in the file.  The file length does not include any  ^Z  or  other
  898.   characters  used to pad the last block. All unused bytes in packet 0 must be
  899.   set to 0.
  900.  
  901.   After the file has been transmitted, the receiver asks for the next file  by
  902.   sending a 'C'.
  903.  
  904.   Transmission of a null pathname terminates the YMODEM protocol.
  905.  
  906.  
  907.   Here is an example of YMODEM:
  908.  
  909.  
  910.   SENDER                                 RECEIVER
  911.                                           ACK
  912.                                           C
  913.   STX 02 FD Data[1024] CRC CRC
  914.                                           ACK
  915.   SOH 03 FC Data[128] CRC CRC
  916.                                           ACK
  917.   SOH 04 FB Data[100] ^Z[28] CRC CRC
  918.                                           ACK
  919.   EOT
  920.                                           NAK
  921.   EOT
  922.                                           ACK
  923.                                           C
  924.   SOH 00 FF NUL[128] CRC CRC
  925.  
  926.  
  927.  
  928.                                           ACK
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  PPL4C Users Manual                                                Page 14
  953.   7.0 ZMODEM
  954.  
  955.  
  956.   ZMODEM was developed for UNIX by Chuck Forsberg of Omen Technology  for  the
  957.   public  domain  under  contract by Telenet.  The ZMODEM protocol description
  958.   and  UNIX  source  code  are  public  domain.  Furthermore,  no   licensing,
  959.   trademark, or copyright restrictions apply to the use of the ZMODEM protocol
  960.   or the Unix source code.
  961.  
  962.   The  following  description  is  meant  as  an  overview  only of the ZMODEM
  963.   protocol.  A more complete description can be obtained on CompuServe (in the
  964.   protocols library of the IBMCOM forum) or  directly  from  Omen  Technology,
  965.   Inc. (503-621-3406 Voice).
  966.  
  967.   ZMODEM  is  complex.  For PC to PC file transfers, it is certainly overkill.
  968.   Our protocol library  implements  the  original  public  domain  UNIX  based
  969.   ZMODEM, with a few minor exceptions that have no impact for use between PCs.
  970.  
  971.   7.2 Link Escape Encoding
  972.  
  973.   ZMODEM  send  and  receives binary data without the use of a length count by
  974.   using a technique known as "data escape encoding".  A special character ZDLE
  975.   (hex 18) is used to mark the beginning of frames.
  976.  
  977.   The receiving program decodes any sequence of ZDLE followed by a  byte  with
  978.   bit  6  set  and bit 5 clear to the control character consisting of the byte
  979.   with bit 6 inverted.  This allows the  transmitter  to  escape  any  control
  980.   character including ZDLE itself.
  981.  
  982.   7.3 ZMODEM Headers
  983.  
  984.   ZMODEM  frames  begin  with  a hexidecimal or binary header. A header always
  985.   begins with a frame type and is followed by either a 4 byte file position or
  986.   4 bytes of flags. The order of bytes in the header is as follows:
  987.  
  988.   0x00 Type field: Frame type (1 byte) 0x01 Data bytes: F3 or P0 0x02 F2 or P1
  989.   0x03 F1 or P2 0x04 F0 or P3
  990.  
  991.   where F = flags, P = file position
  992.  
  993.   7.3.1 16-Bit CRC Binary Headers
  994.  
  995.   A binary header begins with the sequence ZPAD, ZDLE,  ZBIN  with  the  frame
  996.   type  byte  and  four flag or position bytes being ZDLE encoded.  A two byte
  997.   CRC is computed from the frame type through the flag/position bytes  and  is
  998.   also  ZDLE  encoded.  Zero  or  more  16  bit CRC binary data subpackets may
  999.   follow.
  1000.  
  1001.   ZPAD ZDLE ZBIN TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC1 CRC2
  1002.  
  1003.  
  1004.   7.3.2 32-Bit CRC Binary Headers
  1005.  
  1006.   A 32 bit CRC Binary header is identical to a 16 bit CRC Binary Header except
  1007.   ZBIN is replaced by ZBIN32 and four bytes of CRC are sent. Zero or  more  32
  1008.   bit CRC binary data subpackets may follow.
  1009.  
  1010.   ZPAD ZDLE ZBIN32 TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC1 CRC2 CRC3 CRC4
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  PPL4C Users Manual                                                Page 15
  1021.   7.3.3 Hexidecimal Headers
  1022.  
  1023.   The sender will use hexidecimal headers when they are not followed by binary
  1024.   data   subpackets.   The  receiver  will  also  send  responses  headers  in
  1025.   hexidecimal. Any data packet following a hexidecimal header uses CRC-16.
  1026.  
  1027.   A carriage return and line feed are appended to hexidecimal header.  An  XON
  1028.   character  is  also  appended except for ZACK and ZFIN headers. Zero or more
  1029.   data subpackets will follow depending on the frame type.
  1030.  
  1031.   ZPAD ZPAD ZDLE ZHEX TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC1 CRC2 CR LF XON
  1032.  
  1033.   Note that TYPE, F3...F0, CRC1, and CRC2 are each  sent  as  two  hexidecimal
  1034.   digits.
  1035.  
  1036.   7.4 Binary Data Subpackets
  1037.  
  1038.   A  binary  data  subpacket may immediately follow a binary header.  A binary
  1039.   data packet will contain 1024 bytes of data or less.
  1040.  
  1041.   The data bytes are ZDLE encoded and are terminated by  ZDLE,  FrameEnd,  and
  1042.   ZDLE  encoded  CRC bytes.  The CRC is summed from the data bytes through the
  1043.   FrameEnd.
  1044.  
  1045.   7.4.1 Frame Ends
  1046.  
  1047.   Data packets are terminated by one of several Frame End headers.
  1048.  
  1049.   7.4.1.1 ZCRCG
  1050.  
  1051.   A ZCRCG data packet means "do not respond unless an error is detected".
  1052.  
  1053.   7.4.1.2 ZCRCQ
  1054.  
  1055.   A ZCRCQ data packet requires a ZACK response with the  file  offset  of  the
  1056.   receiver  if no error, otherwise a ZRPOS response with the last correct file
  1057.   offset.
  1058.  
  1059.   7.4.1.3 ZCRCW
  1060.  
  1061.   A ZCRCW data packets expect a response before the next packet is sent.
  1062.  
  1063.   7.4.1.4 ZCRCE
  1064.  
  1065.   A ZCRCE data subpacket is used to end the end  of  the  file.  It  does  not
  1066.   require a response unless an error is detected.
  1067.  
  1068.   7.5 ZMODEM Startup
  1069.  
  1070.   ZMODEM  timing  is  receiver  driven.  The sender may send a ZRQINIT header,
  1071.   which requests the receiver to immediately send a ZRINIT.
  1072.  
  1073.   The ZMODEM receiver transmits a ZRINIT header to initiate file transfers, or
  1074.   a ZCHALLENGE header to verify the  idenity  of  the  sending  program.   The
  1075.   receiver  retransmits its header at 10 second intervals for up to one minute
  1076.   before aborting.
  1077.  
  1078.   If the receiver receives a ZRQINIT header, it responds by sending (again)  a
  1079.   ZRINIT  header.   If  the sender receives the ZCHALLENGE header, it responds
  1080.   with a ZACK using the data in P0...P3.
  1081.  
  1082.   The sender may also send a ZSINIT frame to define  the  receivers  Attention
  1083.   sequence.
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  PPL4C Users Manual                                                Page 16
  1089.   7.6 File Transmission
  1090.  
  1091.   A  file  transmission  is initiated when the sender transmits a ZFILE header
  1092.   followed by a ZCRCW data subpacket containing the file  name,  file  length,
  1093.   file modification date, and file modification time.
  1094.  
  1095.   If  appropriate, the receiver responds with a ZSKIP header which directs the
  1096.   sender to skip to the next file.
  1097.  
  1098.   If the receiver already has a file with the same name and  length,  it  will
  1099.   respond with a ZCRC header which requests that the sender perform a (32 bit)
  1100.   CRC  on  the file and transmit back to the receiver.  The receiver then uses
  1101.   this information to determine whether to accept the file or not.
  1102.  
  1103.   The receiver initiates transmission of a file  by  sending  a  ZRPOS  header
  1104.   which  specifies  the  starting offset in bytes.  This allows an interrupted
  1105.   file transfer to be resumed.
  1106.  
  1107.   The sender transmits a ZDATA binary header with file  position  followed  by
  1108.   one or more data subpackets.
  1109.  
  1110.   The  receiver compares the file position in the ZDATA header with the number
  1111.   of bytes already received. If they do not agree, a ZRPOS header is  sent  to
  1112.   resynchronize the sender at the right position in the file.
  1113.  
  1114.   After  all  data  has been transmitted, a ZEOF header is sent containing the
  1115.   ending file offset.  The receiver compares this number with  the  number  of
  1116.   bytes  received.  If they match, the file is closed and the receiver reponds
  1117.   with a ZRINIT.  If the receiver has not received all bytes, then the ZEOF is
  1118.   ignored since another ZDATA is coming.   A  ZFERR  header  is  sent  if  the
  1119.   receiver cannot close the file.
  1120.  
  1121.   7.7 ZMODEM Termination
  1122.  
  1123.   A  ZFIN header is sent in order to close the session.  which is acknowledged
  1124.   by a ZFIN header. Then the two characters "OO" are sent by the  sender.  The
  1125.   receiver waits briefly for the "OO" then exits even if not received.
  1126.  
  1127.   7.7.1 Session Abort Sequence
  1128.  
  1129.   The  Attention  sequence  is used to interrupt a data transmission so that a
  1130.   cancel sequence can be sent (8 CANs and 10 BSs).
  1131.  
  1132.   7.8 ZMODEM Streaming
  1133.  
  1134.   Since PCs can overlap serial I/O and disk I/O, full streaming is possible.
  1135.  
  1136.   The sender begins its data transmission with  a  ZDATA  header  followed  by
  1137.   ZCRCG  data  sub packets.  If the receiver detects an error, it executes the
  1138.   Attention sequence and transmits a ZRPOS header.
  1139.  
  1140.   A ZACK header with an address that disagrees with the sender is  ignored  by
  1141.   the receiver
  1142.  
  1143.   A  ZFIN, ZABORT, or TIMEOUT terminates the session, while a ZSKIP terminates
  1144.   the transmission of the file.
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  PPL4C Users Manual                                                Page 17
  1157.   7.9 Attention Sequence
  1158.  
  1159.   The receiving program transmits the Attention sequence whenever  it  detects
  1160.   an error and needs to interrupt the sending program.
  1161.  
  1162.   The  default  Attention string value is empty. The receiver resets Attention
  1163.   sequence to empty before each transfer session.
  1164.  
  1165.   The sender specifies the Attention sequence in the ZSINIT frame.
  1166.  
  1167.   7.10 Frame Types
  1168.  
  1169.   The  numeric  values for the values shown in boldface are given in zmodem.h.
  1170.   Unused bits and unused bytes in the header (ZP0...ZP3) are set to 0.
  1171.  
  1172.   7.10.1 ZRQINIT
  1173.  
  1174.   Transmitted  by  the  sender to request that the receiver transmits a ZRINIT
  1175.   header.
  1176.  
  1177.   ZF0 contains ZCOMMAND if the sender is  attempting  to  send  a  command,  0
  1178.   otherwise.
  1179.  
  1180.   7.10.2 ZRINIT
  1181.  
  1182.   Transmitted  by  the  receiver.  ZF0  and  ZF1 contain the bitwise OR of the
  1183.   receiver flag bytes. The receiver flag bits and PPL default settings are:
  1184.  
  1185.    CANCRY  = 0x08   /* Can decrypt - NO */
  1186.    CANFDX  = 0x01   /* Can do full duplex - YES */
  1187.    CANOVIO = 0x02   /* Can receive data during disk I/O -YES */
  1188.    CANBRK  = 0x04   /* Can send a break signal - YES */
  1189.    CANCRY  = 0x08   /* Can decrypt - NO */
  1190.    CANLZW  = 0x10   /* Can uncompress - NO */
  1191.    CANFC32 = 0x20   /* Can use 32 bit Frame Check - YES */
  1192.    ESCCTL  = 0x40   /* Expects control chars to be  escaped  NO */
  1193.    ESC8    = 0x80   /* Expects 8th bit to be escaped - NO */
  1194.  
  1195.   ZP0  and  ZP1  contain  the  size of the receiver's buffer in bytes, or 0 if
  1196.   nonstop I/O is allowed.
  1197.  
  1198.   7.10.3 ZSINIT
  1199.  
  1200.   Transmitted by the sender. Contains the foloowing flags followed by a  ZCRCW
  1201.   terminated binary data subpacket.
  1202.  
  1203.   /* ZF0  bit  masks */
  1204.   TESCCTL = 0x40  /* Expects control bytes to be escaped */
  1205.   TESC8   = 0x80  /* Expects 8th bit to be escaped */
  1206.  
  1207.   The data subpacket contains the (null terminated) Attention sequence.
  1208.  
  1209.   7.10.4 ZACK
  1210.  
  1211.   Transmitted by  the  receiver.   Acknowledges  a  ZSINIT  frame,  ZCHALLENGE
  1212.   header,  or  ZCRCQ  /  ZCRCW  data  subpacket.   ZP0 to ZP3 contain the file
  1213.   offset.  The response ZACK to a ZCHALLENGE contains the same 32  bit  number
  1214.   received in the ZCHALLENGE header.
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  PPL4C Users Manual                                                Page 18
  1225.   7.10.5 ZFILE
  1226.  
  1227.   Transmitted  by  the  sender.  This ZFILE frame signifies the beginning of a
  1228.   file transmission. ZF0, ZF1, and ZF2 flags contain options.  A value of 0 in
  1229.   implies no special treatment.  Options  specified  by  the  sender  (to  the
  1230.   receiver) over ride any options specified by the receiver except for ZCBIN.
  1231.  
  1232.  
  1233.   7.10.5.1 ZF0: Conversion Option
  1234.  
  1235.   ZCBIN: "Binary" transfer - inhibit conversion unconditionally
  1236.  
  1237.   ZCNL: Convert received end of line to local end of line convention (CR/LF or
  1238.   NL).
  1239.  
  1240.   ZCRECOV: Resume interrupted file transfer.
  1241.  
  1242.   7.10.5.2 ZF1: Management Option
  1243.  
  1244.   Transfer normally if the receiver can not recognize the Management Option.
  1245.  
  1246.   ZMSKNOLOC: Instructs the receiver to bypass the current file if the receiver
  1247.   does not have a file with the same name.
  1248.  
  1249.   One and only one of the following may be set (defined by ZMMASK).
  1250.  
  1251.   ZMNEWL:  Transfer  the  file  if  the destination file is absent. Otherwise,
  1252.   transfer the file overwriting the destination if the source file is newer or
  1253.   longer.
  1254.  
  1255.   ZMCRC: Compare the source and destination files.  Transfer the file  if  the
  1256.   source and destination file lengths or file polynomials are different.
  1257.  
  1258.   ZMAPND: Append the source file to the end of the existing destination file.
  1259.  
  1260.   ZMCLOB: Replace the existing destination file (if any).
  1261.  
  1262.   ZMDIFF:  Transfer  the  file  if  destination  file  is  missing. Otherwise,
  1263.   transfer the file overwriting destination if files have different lengths or
  1264.   dates.
  1265.  
  1266.   ZMPROT: Transfer the file only if the destination file is  absent  (protects
  1267.   destination file)..
  1268.  
  1269.   ZMNEW:  Transfer  the  file if the destination file is absent. Otherwise, if
  1270.   the source file is newer, transfer the file overwriting the destination.
  1271.  
  1272.   7.10.5.3 ZF2: Transport Option
  1273.  
  1274.   ZTLZW: Do Lempel-Ziv compression. (NOT supported).
  1275.  
  1276.   ZTCRYPT: Do encryption. (NOT supported).
  1277.  
  1278.   ZTRLE: Do run length encoding. (NOT supported).
  1279.  
  1280.   A data subpacket terminated by ZCRCW follows with file  name,  file  length,
  1281.   and modification date.
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  PPL4C Users Manual                                                Page 19
  1293.   7.10.5.4 ZF3: Extended Options
  1294.  
  1295.   ZTSPARS: Special processing for sparse files. (NOT supported).
  1296.  
  1297.   7.10.6 ZSKIP
  1298.  
  1299.   Transmitted  by  the  receiver. Used in response to ZFILE, requests that the
  1300.   sender skip the current file.
  1301.  
  1302.   7.10.7 ZNAK
  1303.  
  1304.   Transmitted by the sender or the receiver. Indicates that  the  last  header
  1305.   was unintelligible.
  1306.  
  1307.   7.10.8 ZABORT
  1308.  
  1309.   Transmitted  by  receiver.   Used  to  terminate  batch  file transfers when
  1310.   requested by the user.  The sender responds with a ZFIN header.
  1311.  
  1312.   7.10.9 ZFIN
  1313.  
  1314.   Transmitted by sender and receiver.  Used by the  sender  to  terminate  the
  1315.   ZMODEM session.  The receiver responds by also sending a ZFIN header.
  1316.  
  1317.   7.10.10 ZRPOS
  1318.  
  1319.   Transmitted  by  receiver: Used to force file transfer to resume at the file
  1320.   offset specified in ZP0...ZP3.
  1321.  
  1322.   7.10.11 ZDATA
  1323.  
  1324.   Transmitted by the sender.  The ZP0...ZP3 flags contain file offset. One  or
  1325.   more data subpackets follow.
  1326.  
  1327.   7.10.12 ZEOF
  1328.  
  1329.   Transmitted  by  the  sender.   Used  to report EOF (end of file). ZP0...ZP3
  1330.   contain the ending file offset.
  1331.  
  1332.   7.10.13 ZFERR
  1333.  
  1334.   Transmitted by the sender or receiver. Used to signify an error  in  reading
  1335.   or writing a file.
  1336.  
  1337.   7.10.14 ZCRC
  1338.  
  1339.   Transmitted  by  both  the  sender and the receiver. Used by the receiver to
  1340.   request a file polynomial.  Used by the sender  to  provide  requested  file
  1341.   polynomial (contained in ZP0...ZP3).
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  PPL4C Users Manual                                                Page 20
  1361.   7.10.15 ZCHALLENGE
  1362.  
  1363.   Transmitted  by  the  receiver.  Used  to  request  that the sender echo the
  1364.   (random) number in flags ZP0...ZP3 in a ZACK frame.
  1365.  
  1366.   7.10.16 ZCOMPL
  1367.  
  1368.   Transmitted by both the sender and the receiver.  Used to  report  that  the
  1369.   request is now completed.
  1370.  
  1371.   7.10.17 ZCAN
  1372.  
  1373.   Transmitted by both sender and receiver. Used to abort.
  1374.  
  1375.   7.10.18 ZFREECNT
  1376.  
  1377.   Transmitted  by  the  sender.  Used  to  request a ZACK frame with the flags
  1378.   ZP0...ZP3 containing the number of free bytes on the current file system.  A
  1379.   zero indicates an abritrarily large amount of free space.
  1380.  
  1381.   7.10.19 ZCOMMAND
  1382.  
  1383.   Transmitted by sender or receiver. It is sent in a binary frame in which ZF0
  1384.   contains zero or a ZCACK1.
  1385.  
  1386.   A ZCRCW data subpacket follows containing  an  zero  terminated  ASCII  text
  1387.   command string.
  1388.  
  1389.   If  the  first  character  of  the  command  is  a !, then it is meant to be
  1390.   executed by the O/S, otherwise it it mean to be executed by the  application
  1391.   program.
  1392.  
  1393.   If  the  receiver  cannot decipher the command, then it immediately responds
  1394.   with a ZCOMPL header (with the error code in ZP0...ZP3).
  1395.  
  1396.   If ZF0 contained a ZCACK1, then the receiver  responds  immediately  with  a
  1397.   ZCOMPL header with 0 status.
  1398.  
  1399.   Otherwise,  the receiver responds with a ZCOMPL header when the operation is
  1400.   completed with the exit status of the command in ZP0...ZP3.
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  PPL4C Users Manual                                                Page 21
  1429.   7.11 Examples
  1430.  
  1431.   Example 1:
  1432.  
  1433.   One file, no errors, no CHALLENGE.
  1434.  
  1435.  
  1436.   SENDER                   RECEIVER
  1437.  
  1438.   ZRQINIT(0)
  1439.                           ZRINIT
  1440.   ZFILE
  1441.                           ZRPOS
  1442.   ZDATA data ...
  1443.   ZEOF
  1444.                           ZRINIT
  1445.   ZFIN
  1446.                           ZFIN
  1447.   OO
  1448.  
  1449.   Example 2: Challenge and Command Download
  1450.  
  1451.  
  1452.   SENDER                   RECEIVER
  1453.  
  1454.   ZRQINIT(ZCOMMAND)
  1455.                           ZCHALLENGE(random-number)
  1456.   ZACK(same-number)
  1457.                           ZRINIT
  1458.   ZCOMMAND
  1459.   ZDATA
  1460.                           (Performs Command)
  1461.                           ZCOMPL
  1462.   ZFIN
  1463.                           ZFIN
  1464.   OO
  1465.  
  1466.  
  1467.   7.12 ZFILE Frame Information
  1468.  
  1469.   7.12.1 Filename
  1470.  
  1471.   Null terminated ASCII string. Path information is optional but not used.
  1472.  
  1473.   7.12.2 File Length (optional)
  1474.  
  1475.   The file length is stored as a decimal string. Used by the  ZMODEM  receiver
  1476.   as an estimate only.
  1477.  
  1478.   7.13.3 Modification Date (optional)
  1479.  
  1480.   The  modification  date  is  sent  as  an  octal  number giving the time the
  1481.   contents of the file were last changed measured in seconds from Jan  1  1970
  1482.   Universal Coordinated Time (GMT).  A date of 0 implies the modification date
  1483.   is unknown.
  1484.  
  1485.   A  single  space  separates  the modification date from the file length. The
  1486.   file information is terminated by a null.
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  PPL4C Users Manual                                                Page 22
  1497.   8.0 Problems
  1498.  
  1499.  
  1500.   If you cannot get your application to run properly, first  compile  and  run
  1501.   the  demonstration  program TERM provided on your distribution disk.  If you
  1502.   are using a null modem cable or a non-programmable modem,  be  sure  not  to
  1503.   define  AT_COMMAND_SET  in  TERM.CFG.   If  you are using a Hayes compatible
  1504.   modem, then do define AT_COMMAND_SET.  If you are using a programmable modem
  1505.   which is not Hayes compatible,  then  you  must  modify  the  initialization
  1506.   string for your particular modem.
  1507.  
  1508.   If your application does not run but TERM runs correctly, then you have most
  1509.   likely  made  a  programming  mistake  in  your  application.   MarshallSoft
  1510.   Computing cannot debug your  application,  especially  over  the  telephone!
  1511.   However,  consider each of the following when searching for an error in your
  1512.   application.
  1513.  
  1514.   1.  Did you include the "uses PPL4C" statement ?
  1515.  
  1516.   2.  Is your receive buffer large enough ? If you are using 1K data blocks in
  1517.   YMODEM,  then  your  receive  buffer should be at least 1K (2K if baud rates
  1518.   above 38400 are to be used).
  1519.  
  1520.   4.  Have you selected too high a baud rate (if you are using a slow PC) ? If
  1521.   only one COM port is being run, you should be able to run at 38400  baud  on
  1522.   8088 machines and 115200 on most 286 and all 386 and 486 machines.
  1523.  
  1524.   7.   Are  you attempting to run another application in the background ?  Try
  1525.   running without any other programs running in the background (unload all TSR
  1526.   programs).
  1527.  
  1528.   6.  If you are running two COM ports simultaneously, are you using  separate
  1529.   receive buffers ? (you should).
  1530.  
  1531.   7.   Did SioReset return a zero value ?  If not, then you must call SioReset
  1532.   again. See TERM.C for an example.
  1533.  
  1534.   8.  Did you send the proper initialization string to your modem  ?  Did  you
  1535.   set DTR and RTS ? (you should).
  1536.  
  1537.   9.   Do  you  have more than one COM1 port, etc.  For example, if you have a
  1538.   COM1 port on your motherboard, you cannot add another  COM1  port  or  modem
  1539.   board that uses COM1 without first disabling the COM1 on the motherboard.
  1540.  
  1541.   10. Are you passing the proper segment of the receive (or transmit) buffer?.
  1542.   See SIMPLE.C or TERM.C for an example.
  1543.  
  1544.   11. Is the other side running the same protocol?
  1545.  
  1546.   12. Are you using 8 data bits. All the protocols except ASCII require 8 data
  1547.   bits.
  1548.  
  1549.   Registered users can call 205-881-4630 from 1:30 PM to 9:30  PM  CST  Monday
  1550.   through Friday for help. We are also often here on the weekend!
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  PPL4C Users Manual                                                Page 23
  1565.   9.0 Legal Issues
  1566.  
  1567.   9.1 Registration
  1568.  
  1569.  
  1570.   If you wish to register the PPL4C library, please send $40 plus $3  S&H  ($6
  1571.   outside of North America) to:
  1572.  
  1573.            MarshallSoft Computing, Inc.
  1574.            Post Office Box  4543
  1575.            Huntsville AL 35815
  1576.  
  1577.   Multiple copies are available: $35 for 3 to 9, $30 for 10 to 19, and $25 for
  1578.   20  or  more.  A site license is also available for $495 (includes 5 sets of
  1579.   printed documentation). We pay shipping.
  1580.  
  1581.   We accept American Express (account number, expiration date, exact  name  on
  1582.   your card, and complete AmEx billing address required), checks in US dollars
  1583.   drawn  on  a  US  bank, purchase orders (POs) from recognized US schools and
  1584.   companies listed in Dun & Bradstreet, and  COD  (street  address  and  phone
  1585.   number  required)  within  the  USA  (plus a $3 COD charge).  Print the file
  1586.   PPL4C.INV if an invoice is needed.
  1587.  
  1588.   You can also order PPL4C from The Public Software Library  (PSL)  with  your
  1589.   MC,  Visa,  AmEx,  or  Discover card by calling 800-242-4PSL (from overseas:
  1590.   713-524-6394) or by FAX at 713-524-6398 or  by  CompuServe  at  [71355,470].
  1591.   THESE NUMBERS ARE FOR ORDERING ONLY. The product number for PPL4C is 11782.
  1592.  
  1593.   If  you  wish to update from an older version of PPL4C, send $20 plus $3 S&H
  1594.   ($6 outside of North  America).   Updates  must  be  ordered  directly  from
  1595.   MarshallSoft Computing.
  1596.  
  1597.   The registered package includes:
  1598.  
  1599.   o  C/C++ source code for the library (including ZMODEM).
  1600.   o  Printed Users Manual.
  1601.   o  Telephone and BBS support for one year.
  1602.   o  Script compiler & interpreter.
  1603.   o  Script compiler (BUILDER) creates script binaries from source.
  1604.   o  Script interpreter (SI) executes script binaries.
  1605.  
  1606.   Print the file INVOICE.DOC if an invoice is needed. The registered user will
  1607.   receive the latest version of PPL4C shipped by two day priority mail (packet
  1608.   airmail  overseas).   A  3.5"  (720KB)  diskette  is provided unless a 5.25"
  1609.   (360KB) diskette is requested.
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  PPL4C Users Manual                                                Page 24
  1633.   9.3 License
  1634.  
  1635.  
  1636.   MarshallSoft Computing, Inc. grants the registered user of PPL4C  the  right
  1637.   to  use  one copy of the PPL4C library (in object form) on a single computer
  1638.   in the development of any software product (other  than  libraries  such  as
  1639.   PPL4C).  The  user  may not use the library on more than one computer at the
  1640.   same time.  The source code for the  library  (XYMODEM.C  and  ZMODEM.C)  is
  1641.   copyrighted by MarshallSoft and may not be released in whole or in part.
  1642.  
  1643.   Products developed using PPL4C can include the object form  of  the  library
  1644.   and may be distributed without any royalty.
  1645.  
  1646.  
  1647.   9.4 Warranty
  1648.  
  1649.  
  1650.   MARSHALLSOFT COMPUTING, INC.  DISCLAIMS  ALL  WARRANTIES  RELATING  TO  THIS
  1651.   SOFTWARE,  WHETHER  EXPRESSED  OR  IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
  1652.   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR  PURPOSE,
  1653.   AND  ALL  SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER
  1654.   MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN  INVOLVED  IN  THE
  1655.   CREATION,  PRODUCTION,  OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY
  1656.   INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT  OF  THE  USE  OR
  1657.   INABILITY  TO  USE  SUCH  SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.  HAS
  1658.   BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL
  1659.   MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH  DAMAGES  EVER  EXCEED
  1660.   THE  PRICE  PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM
  1661.   OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY
  1662.   AND PERFORMANCE OF THE SOFTWARE.
  1663.  
  1664.   Some states do not allow  the  exclusion  of  the  limit  of  liability  for
  1665.   consequential  or  incidental damages, so the above limitation may not apply
  1666.   to you.
  1667.  
  1668.   This agreement shall be governed by the laws of the  State  of  Alabama  and
  1669.   shall  inure  to  the  benefit  of  Marshallsoft  Computing,  Inc.   and any
  1670.   successors, administrators, heirs and  assigns.  Any  action  or  proceeding
  1671.   brought  by either party against the other arising out of or related to this
  1672.   agreement shall be brought only in a STATE or  FEDERAL  COURT  of  competent
  1673.   jurisdiction  located in Madison County, Alabama. The parties hereby consent
  1674.   to in personam jurisdiction of said courts.
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  PPL4C Users Manual                                                Page 25
  1701.   11.0 Summary
  1702.  
  1703.   11.1 Revision History
  1704.  
  1705.  
  1706.   Version 1.0 - 12 February 1995 - original release.
  1707.  
  1708.   XMODEM  and  YMODEM  in  PPL4C is based on version 4.2 of the Communications
  1709.   Library for C/C++ (PCL4C). ZMODEM is new.
  1710.  
  1711.   12.0 Other MarshallSoft Computing Products for C/C++
  1712.  
  1713.  
  1714.   12.1 The Personal Communications Library for C/C++
  1715.  
  1716.  
  1717.   The  Personal  Communications  Library  for C/C++ (PCL4C) is an asynchronous
  1718.   communications  library  designed  for   experienced   software   developers
  1719.   programming in C and/or C++. The PCL features:
  1720.  
  1721.   o 33+ communications and support functions.
  1722.   o Support for the high performance INS16550 UART.
  1723.   o Supports hardware (RTS/CTS) flow control.
  1724.   o Interrupt driven tranmitter (optionally) & receiver.
  1725.   o Supports 300 baud to 115,200 baud.
  1726.   o Supports COM1 through COM20.
  1727.   o Adjustable receive queues from 8 bytes to 32 KB.
  1728.   o Control-BREAK error exit.
  1729.   o 17 communications error conditions trapped.
  1730.   o Supports most dumb multiport board such as those by Digiboard,  BOCA,  and
  1731.     GTEK.
  1732.   o Allows 4 to 20 ports to run concurrently.
  1733.   o Complete modem control & status.
  1734.   o Written in assembly language for small size & high speed.
  1735.   o Terminal program featuring XMODEM, YMODEM, & YMODEM-G.
  1736.  
  1737.   The  Personal Communications Library for C/C++ (PCL4C) is available for $65
  1738.   plus $3 S&H ($6 S&H overseas).
  1739.  
  1740.  
  1741.   12.2 The LZW Data Compression Library for C/C++
  1742.  
  1743.   LZW4C  consists  of  a  variable  code  size  implementation  of   the   LZW
  1744.   (Lempel-Ziv-Welch)  algorithm  for  compressing and decompressing data.  LZW
  1745.   does particularly  well  on  text  files,  achieving  better  than  a  50  %
  1746.   compression ratio for many files.
  1747.  
  1748.   The  LZW  algorithm  is  considered  to  be  one of the best general purpose
  1749.   algorithms  available  today.   The  new  high  speed  modems  that   employ
  1750.   on-the-fly  data  compression  (such as MNP 5.0 & the V.42 bis international
  1751.   standard) use the LZW algorithm, as well as such well known utility programs
  1752.   such as PKZIP.
  1753.  
  1754.   The LZW Data Compression Library for C/C++ is available for $45 plus $3 S&H
  1755.   ($6 overseas).
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  PPL4C Users Manual                                                Page 26
  1769.  
  1770.